I'm not fond of this change, I think it'd be better to have some kind of Result that has both contents and structured content:

• we could still return a collection of content's (and add structured content if the result has some)
• at some point we will probably only return structured content.

For example:

StructuredContentResult {
  public StructuredContent
}

You mean something like

StructuredContentResult implements CallToolResult {
  public StructuredContent
  public array $contents
}

ContentResult implements CallToolResult {
  public array $contents
}

interface CallToolResult extends \JsonSerializable{
}

Then we can expect instance of CallToolResult interface as return and maybe skip

/** @var array<int, TextContent|ImageContent|EmbeddedResource|AudioContent|StructuredContent> $formattedResult */
$formattedResult = $toolReference->formatResult($result);

and expect user to return proper response from tool?

at some point we will probably only return structured content.

Structured content is not required while outputSchema is not set, and I can argue that for some tasks text response works better.
At least for now content response required even if structuredContent is set.

This implementation is far from best, so if you could steer me in right direction would be great.

I used it in my browser-mcp tools, most crucial part was ability to return proper tool usage errors with hints to help model correct tool calls. Structured content provided no improvements for tool calling and quality so I just removed it from final version.

I'm using this:

<?php

namespace ApiPlatform\Mcp\Schema\Result;

use Mcp\Schema\JsonRpc\ResultInterface;

class StructuredContentResult implements ResultInterface
{
    /**
     * Create a new StructuredContentResult.
     *
     * @param array     $structuredContent The JSON content
     * @param ResultInterface $result A traditional result
     */
    public function __construct(
        public array $structuredContent,
        public readonly ?ResultInterface $result = null
    ) {
    }

    public function jsonSerialize(): mixed
    {
        return ['structuredContent' => $this->structuredContent] + ($this->result?->jsonSerialize() ?? []);
    }
}

This is merely a suggestion :).

I changed implementation, removed some changes.

Now we have CallToolResultInterface and 2 classes implementing it:

• CallToolResult as our general result class
• CallToolStructuredContentResult as SturcturedContent result which pretty much decorates CallToolResult

Tested on my Browser MCP it's working as expected.

Also added Unit tests to cover behavior.

As for example of usage, maybe we can add one after #88 merged as they go hand by hand together.

@chr-hertel @CodeWithKyrian could you take a look when will get time, it's ready for proper CR now.

I'm a bit confused - the PR description doesn't match the code or do I miss something?

I like the idea of enabling tools to return the CallToolResult optionally if they want to have more control, but let's stick with one implementation here.

If we patch it in the lib we don't need an additional decoration, but can extend the CallToolResult with an optional structure argument, that is omitted in case it's empty. That would be also more consistent with what we have in other data classes and makes it easier in change scenarios. currently spec changes are only additive for example and users relying on using those classes would need to change.

I'm a bit confused - the PR description doesn't match the code or do I miss something?

Yeah, I changed implementation a lot after previous comment and did rework, I can update it.
Comments here describe main idea more.

If we patch it in the lib we don't need an additional decoration, but can extend the CallToolResult with an optional structure argument, that is omitted in case it's empty. That would be also more consistent with what we have in other data classes and makes it easier in change scenarios. currently spec changes are only additive for example and users relying on using those classes would need to change.

Okay, gonna rework to keep single CallToolResult with optional structuredContent.

I like the idea of enabling tools to return the CallToolResult optionally if they want to have more control, but let's stick with one implementation here.

That was actually even more beneficial for me to return proper isError to LLM in response with hints and error explanation so it could do correction, if isError=false always returned as it is now LLM don't always understand what happened and that it needs to correct tool call.

@chr-hertel Moved structuredContent to CallToolResult. Fixed description. Updated unit tests accordingly. Tested responses in inspector, works as expected.